<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
<TITLE>Product installation guidelines</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<h2>Product installation guidelines</h2>
<p>The platform provides standard tools for updating and extending
products.&nbsp; In order to participate in the platform mechanisms for updating
and extending products, your packaged product should follow the following
guidelines.&nbsp; This will allow your product to peacefully
coexist with, or even enhance, other Eclipse based products.</p>
<p>Consider again the sample directory structure for the acmeweb product:</p>
<pre>acmeweb/
	acmeweb.exe
	eclipse/	
		.eclipseproduct
		artifacts.xml	
		eclipse.exe	
		install.ini	
		.config/	
			platform.cfg
		jre/
		dropins/
		features/	
			com.example.acme.acmefeature_1.0.0/
				feature.xml
			...
		plugins/
			com.example.acme.acmefeature_1.0.0/
				plugin.xml
				about.ini
				about.html
				about.mappings
				about.properties
				acme.png
				plugin_customization.ini
				splash.bmp
				welcome.xml
			com.example.acme.acmewebsupport_1.0.0/
			...
		links/
			...
		p2/
			...</pre>			

<p>Where did these files come from?&nbsp; Let's look at the product content from
the perspective of the development team.&nbsp; The installed files can be
grouped into five main categories:</p>
<ul>
  <li>top-level product files (such as the acmeweb.exe)</li>
  <li>product features and plug-ins</li>
  <li>the Eclipse platform itself (this includes the contents of the p2 and configuration folder)</li>
  <li>the Java runtime environment (JRE)</li>
  <li>files generated by the installation process itself</li>
</ul>
<p>A proper installation script will produce the appropriate directory structure
by doing the following:</p>
<ul>
  <li>allow the user to specify the top level directory of the install (such as <b>c:\acmeweb.&nbsp;
    </b>We will refer to it as <b>acmeweb</b> for the remaining steps.)</li>
  <li>ensure that a product is not already installed in the location</li>
  <li>copy the files as follows:
    <ul>
      <li>Top-level product files are copied to <b>acmeweb</b></li>
      <li>Eclipse files are copied to <b>acmeweb/eclipse </b>using the expected
        feature and plugin directory structures</li>
      <li>JRE files are copied to <b>acmeweb/eclipse/jre</b>.&nbsp; If a JRE is
        already located elsewhere, then the application shortcut should be setup
        to invoke eclipse with the <b>-vm</b> command line argument so that the
        location of the JRE is known by the platform</li>
      <li>Product features and plug-ins are copied to <b>acmeweb/eclipse/features</b>
        and <b>acmeweb/eclipse/plugins</b></li>
      <li>Platform configuration information is copied to <b>acmeweb/eclipse/configuration</b></li>
      <li>Platform update support information is copied to <b>acmeweb/eclipse/p2</b></li>      
    </ul>
  </li>
  <li>create a marker file, <b>.eclipseproduct</b>, in <b>acmeweb/eclipse</b>.&nbsp;
    The marker file is a <b>java.util.Properties</b> format file that indicates
    the name, id, and version of the product.</li>
  <li>store any necessary install info (user, license, date) that is to be shown
    in the about dialog in <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.0/about.mappings</b></li>
  <li>if the primary feature mechanism (pre R3.0) is used to define the product, replace the 
  <b>acmeweb/eclipse/install.ini</b> with one that sets the property <b>feature.default.id
    </b>to the product's primary feature</li>
  <li>invoke the product executable using the <b>-initialize</b> option.&nbsp;
    This causes the platform to quietly perform all time-consuming first-time
    processing and cache the results, so that when the user starts the product
    it comes up promptly in an open-for-business state.</li>
</ul>
<h3>Multi-user issues</h3>
<p>When a product is installed with the intention of sharing the installation among multiple users,
care must be taken to separate individual user's data (such as the <b>workspace</b>
directory) from the shared product install directory.</p>
<h3>Uninstall issues</h3>
<p>When a product is uninstalled, the following concepts are important.</p>
<ul>
  <li><b>all</b> files in the <b>eclipse/features</b> and <b>eclipse/plugins</b>
    directories should be removed, even if they weren't originally installed by
    the installation program.&nbsp; This ensures that files added by the
    platform installer are removed when the product is removed.</li>
  <li>except for the point above, <b>only</b> those files installed by the
    installation program in other directories should be removed.&nbsp; It is
    important to preserve any important data, such as the <b> workspace</b>
    directory, so
    that reinstalling the product after an uninstall will produce expected
    results.</li>
</ul>
<h3>Reinstalling the product</h3>
<p>When the product is already installed, the installer should allow a service
update or upgrade if one is available.&nbsp; The existence of the product can be
confirmed by looking for <b>acmeweb/eclipse/.eclipseproduct</b>.&nbsp; The
information in this marker file can be used to confirm with the user that the
correct product is being updated.&nbsp; The availability of updates can be
confirmed with pattern matches against feature names.&nbsp; For example, the
presence of <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.1 </b>would
indicate that the 1.0.1 version update had already been applied to the product.</p>
<p>Once the validity of the reinstall is established, the install program should
copy or replace files as needed.&nbsp; If the version of the underlying Eclipse
platform has not changed, there is a good chance that complete directories can
be ignored.&nbsp; The version numbers appended to the platform features and
plugins can be used to determine whether any changes underneath a plug-in or
feature's directory are necessary.&nbsp; </p>
<p>Additional information on installing products can be found in <a href="../reference/misc/eclipse-install.html">How
to write an Eclipse installer</a>.</p>

</BODY>
</HTML>
